<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>ioctl VIDIOC_G_CROP, VIDIOC_S_CROP</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="Video for Linux Two API Specification"
HREF="book1.htm"><LINK
REL="UP"
TITLE="Function Reference"
HREF="r7624.htm"><LINK
REL="PREVIOUS"
TITLE="ioctl VIDIOC_G_CHIP_IDENT"
HREF="r9804.htm"><LINK
REL="NEXT"
TITLE="ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL"
HREF="r10104.htm"></HEAD
><BODY
CLASS="REFENTRY"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Video for Linux Two API Specification: Revision 0.24</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="r9804.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="r10104.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="VIDIOC-G-CROP"
></A
>ioctl VIDIOC_G_CROP, VIDIOC_S_CROP</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN9998"
></A
><H2
>Name</H2
>VIDIOC_G_CROP, VIDIOC_S_CROP&nbsp;--&nbsp;Get or set the current cropping rectangle</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN10002"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN10003"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, struct v4l2_crop *argp);</CODE
></P
><P
></P
></DIV
><DIV
CLASS="FUNCSYNOPSIS"
><P
></P
><A
NAME="AEN10013"
></A
><P
><CODE
><CODE
CLASS="FUNCDEF"
>int ioctl</CODE
>(int fd, int request, const struct v4l2_crop *argp);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN10023"
></A
><H2
>Arguments</H2
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><CODE
CLASS="PARAMETER"
>fd</CODE
></DT
><DD
><P
>File descriptor returned by <A
HREF="r14090.htm"
><CODE
CLASS="FUNCTION"
>open()</CODE
></A
>.</P
></DD
><DT
><CODE
CLASS="PARAMETER"
>request</CODE
></DT
><DD
><P
>VIDIOC_G_CROP, VIDIOC_S_CROP</P
></DD
><DT
><CODE
CLASS="PARAMETER"
>argp</CODE
></DT
><DD
><P
></P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN10043"
></A
><H2
>Description</H2
><P
>To query the cropping rectangle size and position
applications set the <CODE
CLASS="STRUCTFIELD"
>type</CODE
> field of a
<CODE
CLASS="STRUCTNAME"
>v4l2_crop</CODE
> structure to the respective buffer
(stream) type and call the <CODE
CLASS="CONSTANT"
>VIDIOC_G_CROP</CODE
> ioctl
with a pointer to this structure. The driver fills the rest of the
structure or returns the <SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code if cropping is not supported.</P
><P
>To change the cropping rectangle applications initialize the
<CODE
CLASS="STRUCTFIELD"
>type</CODE
> and struct&nbsp;<A
HREF="x6570.htm#V4L2-RECT"
>v4l2_rect</A
> substructure named
<CODE
CLASS="STRUCTFIELD"
>c</CODE
> of a v4l2_crop structure and call the
<CODE
CLASS="CONSTANT"
>VIDIOC_S_CROP</CODE
> ioctl with a pointer to this
structure.</P
><P
>The driver first adjusts the requested dimensions against
hardware limits, i.&nbsp;e. the bounds given by the capture/output window,
and it rounds to the closest possible values of horizontal and
vertical offset, width and height. In particular the driver must round
the vertical offset of the cropping rectangle to frame lines modulo
two, such that the field order cannot be confused.</P
><P
>Second the driver adjusts the image size (the opposite
rectangle of the scaling process, source or target depending on the
data direction) to the closest size possible while maintaining the
current horizontal and vertical scaling factor.</P
><P
>Finally the driver programs the hardware with the actual
cropping and image parameters. <CODE
CLASS="CONSTANT"
>VIDIOC_S_CROP</CODE
> is a
write-only ioctl, it does not return the actual parameters. To query
them applications must call <CODE
CLASS="CONSTANT"
>VIDIOC_G_CROP</CODE
> and
<A
HREF="r10944.htm"
><CODE
CLASS="CONSTANT"
>VIDIOC_G_FMT</CODE
></A
>. When the parameters are unsuitable the application may
modify the cropping or image parameters and repeat the cycle until
satisfactory parameters have been negotiated.</P
><P
>When cropping is not supported then no parameters are
changed and <CODE
CLASS="CONSTANT"
>VIDIOC_S_CROP</CODE
> returns the
<SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
> error code.</P
><DIV
CLASS="TABLE"
><A
NAME="V4L2-CROP"
></A
><P
><B
>Table 1. struct <CODE
CLASS="STRUCTNAME"
>v4l2_crop</CODE
></B
></P
><TABLE
BORDER="0"
FRAME="void"
WIDTH="100%"
CLASS="CALSTABLE"
><COL
WIDTH="25%"
TITLE="C1"><COL
WIDTH="25%"
TITLE="C2"><COL
WIDTH="50%"
TITLE="C3"><TBODY
VALIGN="TOP"
><TR
><TD
>enum&nbsp;<A
HREF="x5953.htm#V4L2-BUF-TYPE"
>v4l2_buf_type</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>type</CODE
></TD
><TD
>Type of the data stream, set by the application.
Only these types are valid here: <CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_CAPTURE</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OUTPUT</CODE
>,
<CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_VIDEO_OVERLAY</CODE
>, and custom (driver
defined) types with code <CODE
CLASS="CONSTANT"
>V4L2_BUF_TYPE_PRIVATE</CODE
>
and higher.</TD
></TR
><TR
><TD
>struct&nbsp;<A
HREF="x6570.htm#V4L2-RECT"
>v4l2_rect</A
></TD
><TD
><CODE
CLASS="STRUCTFIELD"
>c</CODE
></TD
><TD
>Cropping rectangle. The same co-ordinate system as
for struct&nbsp;<A
HREF="r7771.htm#V4L2-CROPCAP"
>v4l2_cropcap</A
> <CODE
CLASS="STRUCTFIELD"
>bounds</CODE
> is used.</TD
></TR
></TBODY
></TABLE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN10092"
></A
><H2
>Return Value</H2
><P
>On success <SPAN
CLASS="RETURNVALUE"
>0</SPAN
> is returned, on error <SPAN
CLASS="RETURNVALUE"
>-1</SPAN
> and the <CODE
CLASS="VARNAME"
>errno</CODE
> variable is set appropriately:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><SPAN
CLASS="ERRORCODE"
>EINVAL</SPAN
></DT
><DD
><P
>Cropping is not supported.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="r9804.htm"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="book1.htm"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="r10104.htm"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>ioctl VIDIOC_G_CHIP_IDENT</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="r7624.htm"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>ioctl VIDIOC_G_CTRL, VIDIOC_S_CTRL</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
